home *** CD-ROM | disk | FTP | other *** search
/ Visual Basic Source Code / Visual Basic Source Code.iso / vbsource / vbdatabs / vbdspec.txt < prev    next >
Text File  |  1999-03-30  |  15KB  |  304 lines
  1. #######################
  2. #### Start of File ####
  3. #######################
  4. ----------------------------------------------------------------- 
  5. File Name: vbdspec.txt 
  6. Contents: VBD Specs Sheet 
  7. ----------------------------------------------------------------- 
  8.  
  9. Variable Block Database Version 1031, Revision A
  10.  
  11. TOPICS:
  12. -------
  13. Overview
  14. VBD File Format
  15. VBD File Specs
  16. Platforms
  17.  
  18. OVERVIEW:
  19. ---------
  20. The Variable Block Database is a file format used to store any
  21. type of variable-length binary data in re-sizeable blocks. The
  22. VBD file format was originally created to store persistent
  23. objects in disk files. A persistent object refers to an object
  24. that saves its state between program invocations. The VBD file
  25. format is not limited to storing persistent objects. Any type of
  26. data can be stored and manipulated in a VBD file. VBD files have
  27. this capability because the methods by which any data type is
  28. stored or retrieved must be defined within the application. 
  29.  
  30. VBD FILE FORMAT:
  31. ----------------
  32. Every VBD file contains a file header, an optional static storage
  33. area, and a dynamic storage area where variable blocks of data
  34. are stored. The file header is composed of six fields and is a
  35. total of 28 bytes in length: 
  36.  
  37. (1) Free space field - stores a pointer to the first block of
  38. de-allocated heap space (4 bytes)
  39.  
  40. (2) End of file field - stores a pointer to the address of the
  41. last byte in the file (4 bytes)
  42.  
  43. (3) Start of heap field - stores a pointer to the start of the
  44. dynamic storage area (4 bytes)
  45.  
  46. (4) Highest block field - stores a pointer to the highest
  47. allocated block (4 bytes)
  48.  
  49. (5) Signature field - signature used to identify the file type (8
  50. bytes)
  51.  
  52. (6) Version field - used to identify the VBD file version
  53. number(4 bytes)
  54.  
  55. This header is used to store information needed by the allocation
  56. functions, a signature, and a version number. The static data
  57. area is used to store fixed data that cannot be altered by any of
  58. the dynamic allocation routines. The size of the static data must
  59. by specified by the application that creates the VBD file. If no
  60. static area is specified then the dynamic data area will start
  61. directly after the VBD file header. 
  62.  
  63. The first 28 bytes of the VBD file (file addresses 0 - 28) will
  64. always contain the VBD header. If a static area is requested by
  65. the application, the static area will occupy the bytes requested.
  66. For example: if an application request 20 bytes to be reserved
  67. for a static data area when the file is created, then bytes 29
  68. through 48 (file addresses 29 - 48) will be reserved. The dynamic
  69. data area will start directly after that and occupy the rest of
  70. the file. A pointer to the start of the dynamic storage area can
  71. be calculated by adding the size of the VBD file header to the
  72. size of the static data area. 
  73.  
  74. The dynamic data area always starts out empty and grows when
  75. variable data blocks are allocated. The "free space", "end of
  76. file", and "start of heap" pointers stored in the VBD file header
  77. are used to maintain the dynamic data area. The "start of heap"
  78. pointer stores the address where the dynamic data area starts
  79. (which is where the static area ends.) The "end of file" pointer
  80. marks the end of the file and points to the location where the
  81. file can be extended during block allocation. 
  82.  
  83. Revision 'A' adds a 32-bit CRC checksum routine used to detect
  84. any bit errors that occur during data storage. The CRC is based
  85. on the Ethernet polynomial of 0x4C11DB7. A checksum is calculated
  86. when data is written to the VBD file, this includes the block
  87. header and the block data. The calculated checksum is then
  88. compared to data actually stored on disk. If the calculated
  89. checksum does not match the actual checksum, a bit error has
  90. occurred during data storage. All bit errors must be handled by
  91. the application since the type of data being stored is not known.
  92.  
  93. Revision 'A' reserves four bytes at the end of each block that
  94. can be used by an application to store a 32-bit checksum with
  95. each block. Each time a new block is allocated space is reserved
  96. for the number of bytes requested plus four additional bytes. The
  97. application is responsible for reading and writing the block
  98. checksum since the type of data being stored is not known. The
  99. use of a block checksum is optional and does not have to be used
  100. to detect bit errors because of the built-in CRC checksum routine
  101. used each time any data is stored. Some applications require the
  102. use of block checksums to maintain the integrity of the file from
  103. one program invocation to the next.
  104.  
  105. When blocks are de-allocated, the block is marked deleted and
  106. left in the file. The size of the file is determined by the
  107. number of blocks allocated and will remain the same no matter how
  108. many blocks are deleted. The number of deleted blocks is
  109. maintained in a non-contiguous list. Each block in the list
  110. points to the next block in the list starting at a specified
  111. address. The "free space" pointer in the VBD file header is used
  112. to store the file address of the block where the free space list
  113. starts. 
  114.  
  115. The "highest block" pointer in the VBD file header is used to
  116. store the address of the highest allocated variable block. It is
  117. used by the application when it needs to index data starting at
  118. the end of the file. 
  119.  
  120. The signature and version fields in the VBD file header must be
  121. set when a new file is created. The signature field is used to
  122. determine if the file is of the correct type. If the "VBDFILE"
  123. signature is not found then it is assumed that this is not a
  124. valid VBD file. The eighth byte is used for all revision changes.
  125. Version 1031 sets the revision letter to 'A' and performs
  126. compatibility checks to ensure backward compatibility with
  127. previous releases. Revision 'A' adds a 32-bit CRC checksum
  128. routine and reserves space at the end of each block for an
  129. application to write a 32-bit check-word. 
  130.  
  131. The version field is to represent this file version number. A
  132. version number is used to indicate that changes have been made to
  133. the application used to create VBD files. Version numbers can be
  134. used inside of an application to conditionally perform certain
  135. operations based on its value. This will ensure backward
  136. compatibility with previous versions. 
  137.  
  138. Variable Block (VB) headers manage all the variable data blocks
  139. created inside the dynamic data area. Block headers are used to
  140. mark the start of a variable data block. Every time a block is
  141. allocated a block header is written to the file. Allocation works
  142. by writing the block header and then reserving a specified number
  143. of bytes for the data that will be stored in the block. Revision
  144. 'A' reserves four bytes at the end of the block to allow the
  145. application to store a block checksum. After the space is
  146. allocated, the application is responsible for writing the data to
  147. the file starting at the address after the block header. Each
  148. block header contains four fields and is a total of 16 bytes in
  149. length: 
  150.  
  151. (1) Check word field - "0x0000FEFE" check word used for file
  152. integrity checks (4 bytes)
  153.  
  154. (2) Length field - block length including the object, block
  155. header, and CRC (4 bytes) 
  156.  
  157. (3) Status field - stores the status of dynamic data stored in
  158. the block (4 byte)
  159.  
  160. (4) Next deleted block field - stores a pointer to the next
  161. deleted block (4 bytes) 
  162.  
  163. The VB header "check word" field represents a 32-bit check word
  164. used for file integrity checks and is used to maintain
  165. synchronization within the VBD creator and the application.
  166. Revision 'A' uses all 32 bits of the block check-word. In
  167. previous releases the upper 16 bits of the block check-word was
  168. reserved for a 16-bit CRC. Revision 'A' implements a 32-bit CRC
  169. routine and reserves four bytes at the end of each block for a
  170. 32-bit checksum. If the check word value is changed, the file
  171. will no longer be compatible with previous releases. 
  172.  
  173. The "length" field stores the length of the object plus the size
  174. of the block header and the size of the block's CRC checksum
  175. value. This field is used to index the file block by block. By
  176. reading this value the application will always k